feat(commerce): add product group with getProducts - #124

commerce extension 에 product 그룹과 extension.commerce.product.getProducts 계약을 추가합니다. 앱이 들고 있는 상품 카탈로그를 표준 확장 함수로 노출할 자리를 만드는 변경이고, 앱 구현과 AppStore 정의는 이 계약을 정본으로 뒤따릅니다.

왜 표준에 자리가 필요한가

• commerce extension 의 그룹은 core / order 뿐이라 상품을 열람하거나 id 로 조회할 함수가 없습니다.
• 주문의 items[].productId 에서 상품으로 이어 갈 표준 경로가 없어, 상품 정보를 쓰는 소비자마다 앱별 함수를 따로 붙여야 했습니다.
• 이 함수는 카탈로그 열람·id 조회입니다. 이름 검색은 받지 않습니다 — searchFilter 에 name 키가 없고, 검색은 별도 표면의 몫입니다.

계약

message CommerceGetProductsInput {
  google.protobuf.Value search_filter = 1;  // 공통 키: productId($in 포함)·state·createdAt
  string since = 2;                          // 이전 응답의 next
  int32 limit = 3;                           // 앱이 기본 10·상한 50
}

message CommerceGetProductsOutput {
  repeated CommerceProduct products = 1;
  string next = 2;
}

message CommerceProduct {
  string id = 1;                    // getOrders items[].productId 와 같은 값
  string name = 2;
  optional double price = 3;        // 0 원 상품이 정상이라 presence
  optional double original_price = 4;
  string currency = 5;
  string state = 6;                 // active / inactive, 모르면 비움
  string image_url = 7;
  repeated string images = 8;
  string product_url = 9;
  string description = 10;
  string summary = 11;
  string vendor = 12;
  string product_type = 13;
  repeated string categories = 14;  // 카테고리 이름
  repeated string tags = 15;
  double created_at = 16;           // 몰에서 상품이 만들어진 시각(epoch ms)
  double updated_at = 17;           // epoch ms — 앱이 저장한 시각일 수 있음
  repeated CommerceProductVariant variants = 18;
}

message CommerceProductVariant {
  string id = 1;                      // items[].variantId · afterExchangeItems[].variantId 와 같은 값
  optional double price = 2;          // 절대가
  optional double stock_quantity = 3; // 재고 미관리면 비움
  repeated CommerceVariantOption options = 4;
}

CommerceAppCapabilities 에 get_products_options 를 더했습니다.

결정한 것

변경 범위

• proto · 생성물(go / ts / zod) · schemaregistry fixture — make proto-generate / make schema-fixture 산출물이고 손으로 고친 파일은 없습니다.
• Go: commerce.FunctionGetProducts, 별칭 Product / ProductVariant / GetProductsInput / GetProductsOutput, 빌더 .GetProducts(handler).
• TS: CommerceProductSchema 등 스키마·타입 4종 export, 함수 레지스트리, proto-contracts 컴파일 검사, proto-field parity 4건.
• 문서: en·ko·ja 가이드와 Go 레퍼런스의 빌더 체인·method 목록.
• changeset: @channel.io/app-sdk-core minor.

fixture 는 두 항목이 바뀝니다 — extension.commerce.product.getProducts 신규와 extension.commerce.core.getAppConfigs 출력(appCapabilities.getProductsOptions). 정의를 복사하는 쪽은 둘 다 옮겨야 합니다.

기존 8개 함수의 스키마·Go 타입은 바뀌지 않습니다. CommerceAppCapabilities 에 필드가 하나 늘 뿐이라 기존 앱은 그대로 컴파일됩니다.

검증

• make build · make lint(lint-ts·lint-go·proto-lint·proto-ssot-check·docs-check) · make format-check · make proto-check(생성물 diff 0) 통과.
• make test-go 통과. 새 테스트 TestGetProductsKeepsZeroPriceAndOmitsUnknownState 가 0 원 price 유지와 미지정 state·originalPrice·stockQuantity 생략을 protojson 출력으로 확인합니다. 함수 수를 세는 테스트(commerce 9, 전체 79)와 smoke spec, 값 타입 별칭 가드(Product·ExchangeableItem 루트)를 함께 갱신했습니다.
• make test-ts 통과(vitest 36 파일 576건, CLI create 스모크).
• scripts/check-public-content.sh 통과.

배포 순서

flowchart LR
  sdk[이 PR 머지] --> tag[go/v0.15.10 태그]
  tag --> def[AppStore commerce 정의에 product 그룹 반영]
  def --> app[앱이 getProducts 구현·광고]
  style sdk fill:#fde68a

• 이 PR 은 단독 배포 가능합니다. 런타임 소비자가 이 repo 에 없습니다.
• Go 태그(go/v0.15.10, 현재 최신 go/v0.15.9)는 머지 후 메인테이너가 밉니다. 소비 앱의 go.mod 는 태그가 난 뒤에 올립니다.
• AppStore 정의는 이 fixture 를 정본으로 복사합니다(위 두 항목). 정의에 product 그룹이 없으면 앱이 광고해도 검증기가 무시하고, getAppConfigs 출력의 appCapabilities 는 additionalProperties: false 라 정의 갱신 전에 앱이 getProductsOptions 를 내면 스키마 위반입니다. 앱 배포는 정의 반영 뒤에 갑니다.
• Go 태그와 npm minor 릴리스는 회수할 수 없습니다. 계약을 고쳐야 하면 후속 minor 로 덮습니다.

리뷰 포인트

• variant.price 를 절대가로 둔 결정 — additional_amount 와 이름은 다르지만 같은 CommerceVariantOption 을 공유합니다.
• state 를 닫힌 enum 으로 둔 것 — 몰 고유 상태를 흡수할지, 앱 매핑에 맡길지.
• getProductsOptions 가 기존 *Options 어휘(입력 필드명 + fieldConfigs dot notation)를 그대로 따르는지.

Summary by CodeRabbit

• 새 기능

  • 커머스 확장에 상품 카탈로그 조회 기능을 추가했습니다.
  • 상품 ID·상태·생성일 기준 필터와 커서 기반 페이지네이션을 지원합니다.
  • 상품, 상품 변형, 가격, 재고, 이미지 및 분류 정보를 조회할 수 있습니다.
  • Go 및 TypeScript에서 상품 조회 계약과 앱 기능 설정을 사용할 수 있습니다.

• 문서

  • 한국어, 영어, 일본어 커머스 확장 문서에 상품 조회 방법, 필터, 페이지 크기 및 페이지네이션 정보를 추가했습니다.
  • 배송 주소 변경 기능에 대한 설명을 보완했습니다.